HTMLMessageBox

The HTMLMessageBox function creates and displays a message box. A message box contains a message and title, plus any combination of command buttons as well as an optional icon.

Unlike the Platform SDK MessageBox function, the HTMLMessageBox function can use a list of custom buttons, automatically remove itself after a given period of time, display a check box to allow the user to prevent the message box from displaying in the future, and automatically handle the Help button. HTMLMessageBox supports displaying rich message text using simple HTML tagging described below.

int HTMLMessageBox(
  HWND hParent,                    // handle to the parent window (can omit if using MFC)
  LPCTSTR messageText,             // pointer to text in the message box
  LPCTSTR titleText = 0,           // pointer to title of the message box
  UINT type = MB_OK,               // style of the message box
  LPCTSTR displayInFutureText = 0, // pointer to display in future text
  HTMLButtonList *pButtonList = 0, // pointer to a custom button list
  int timeoutSeconds = -1,         // automatic timeout time
  int iconResource = -1,           // icon resource ID
  UINT helpID = 0                  // help context ID
);

int HTMLMessageBox(
  HWND hParent,                    // handle to the parent window (can omit if using MFC)
  UINT messageID,                  // string resource ID for the message box text 
  UINT titleID = 0,                // string resource ID for the message box title 
  UINT type = MB_OK,               // style of the message box
  LPCTSTR displayInFutureText = 0, // pointer to display in future text
  HTMLButtonList *pButtonList = 0, // pointer to a custom button list
  int timeoutSeconds = -1,         // automatic timeout time
  int iconResource = -1,           // icon resource ID
  UINT helpID = 0                  // help context ID
);

HWND HTMLMessageBoxModeless(
  HWND hParent,                    // handle to the parent window (can omit if using MFC)
  LPCTSTR messageText,             // pointer to text in the message box
  LPCTSTR titleText = 0,           // pointer to title of the message box
  UINT type = MB_OK,               // style of the message box
  LPCTSTR displayInFutureText = 0, // pointer to display in future text
  HTMLButtonList *pButtonList = 0, // pointer to a custom button list
  int timeoutSeconds = -1,         // automatic timeout time
  int iconResource = -1,           // icon resource ID
  UINT helpID = 0                  // help context ID
);

HWND HTMLMessageBoxModeless(
  HWND hParent,                    // handle to the parent window (can omit if using MFC)
  UINT messageID,                  // string resource ID for the message box text 
  UINT titleID = 0,                // string resource ID for the message box title 
  UINT type = MB_OK,               // style of the message box
  LPCTSTR displayInFutureText = 0, // pointer to display in future text
  HTMLButtonList *pButtonList = 0, // pointer to a custom button list
  int timeoutSeconds = -1,         // automatic timeout time
  int iconResource = -1,           // icon resource ID
  UINT helpID = 0                  // help context ID
);

Parameters

hParent

Handle to the parent window. This parameter can be omitted if using MFC.

messageText

Pointer to a null-terminated string containing the message to be displayed in the message box. Note that you can use simple HTML tagging, as described below.

messageID

A resource ID for the string containing the message to be displayed in the message box. Note that you can use simple HTML tagging, as described below.

titleText

Pointer to a null-terminated string containing the message box title. If NULL or empty, the program name is used.

titleID

A resource ID for the string containing the message box title. If NULL or empty, the program name is used.

displayInFutureText

Pointer to a null-terminated string containing the text for the Don't Display in Future check box. This check box is not displayed if the text is NULL or empty.

pButtonList

Pointer to a custom button list, as described below, or NULL if not used.

timeoutSeconds

The number of seconds to wait before the message box times out, returning HTMLID_TIMEOUT. If this value is 0 or less, no timeout occurs.

iconResource

A resource ID for a custom message box icon, or a value of 0 or less for no icon.

helpID

The help context ID for the message box help, or a value of 0 if none.

type

A combination of flags ORed together to specify the contents and behavior of the dialog box. This parameter can be a set of flags from the following groups:

Buttons Flag
Use one of the following flags to specify the buttons contained in the message box. These flags are ignored if pButtonList contains a button list:

Flag Meaning

MB_ABORTRETRYIGNORE Specifies three push buttons: Cancel, Try Again, and Continue.

HTMLMB_CANCEL Specifies one push button: Cancel.

HTMLMB_CONTINUE Specifies one push button: Continue.

MB_OK Specifies one push button: OK. This is the default.

MB_OKCANCEL Specifies two push buttons: OK and Cancel.

MB_RETRYCANCEL Specifies two push buttons: Retry and Cancel.

MB_YESNO Specifies two push buttons: Yes and No.

MB_YESNOCANCEL Specifies three push buttons: Yes, No, and Cancel.

Flag	Meaning
MB_ABORTRETRYIGNORE	Specifies three push buttons: Cancel, Try Again, and Continue.
HTMLMB_CANCEL	Specifies one push button: Cancel.
HTMLMB_CONTINUE	Specifies one push button: Continue.
MB_OK	Specifies one push button: OK. This is the default.
MB_OKCANCEL	Specifies two push buttons: OK and Cancel.
MB_RETRYCANCEL	Specifies two push buttons: Retry and Cancel.
MB_YESNO	Specifies two push buttons: Yes and No.
MB_YESNOCANCEL	Specifies three push buttons: Yes, No, and Cancel.

Icon Flag
Use one of the following flags to display an icon in the message box. The icon flag is ignored if an icon resource ID is provided by the iconResource parameter.

Flag Meaning

MB_ICONEXCLAMATION,
MB_ICONWARNING An exclamation-point icon appears in the message box.

MB_ICONINFORMATION, MB_ICONASTERISK An icon consisting of a lowercase letter i in a circle appears in the message box.

MB_ICONQUESTION A question-mark icon appears in the message box.

MB_ICONSTOP,
MB_ICONERROR,
MB_ICONHAND A stop-sign icon appears in the message box.

Flag	Meaning
MB_ICONEXCLAMATION, MB_ICONWARNING	An exclamation-point icon appears in the message box.
MB_ICONINFORMATION, MB_ICONASTERISK	An icon consisting of a lowercase letter i in a circle appears in the message box.
MB_ICONQUESTION	A question-mark icon appears in the message box.
MB_ICONSTOP, MB_ICONERROR, MB_ICONHAND	A stop-sign icon appears in the message box.

Default Button Flag
Specify one of the following flags to indicate the default button. If the default button flag is not specified, the first button will be the default button. The default button flag is ignored if a button list is provided.

Flag Meaning

MB_DEFBUTTON1 Make the first button the default button.

MB_DEFBUTTON2 Make the second button the default button.

MB_DEFBUTTON3 Make the third button the default button.

MB_DEFBUTTON4 Make the Help button the default button, regardless of the number of buttons.

Flag	Meaning
MB_DEFBUTTON1	Make the first button the default button.
MB_DEFBUTTON2	Make the second button the default button.
MB_DEFBUTTON3	Make the third button the default button.
MB_DEFBUTTON4	Make the Help button the default button, regardless of the number of buttons.

Return Values

The return value is zero if there is not enough memory to create the message box.

For the HTMLMessageBox functions, if the function succeeds, the return value is the ID of the selected button, such as IDOK, IDCANCEL, IDABORT, IDRETRY, IDIGNORE, IDYES, and IDNO. The value IDOK is also returned by the Continue button. For the HTMLMessageBoxModeless functions, the return value is a handle to the modeless dialog box (HWND), which must be destroyed by the calling program using DestroyWindow.

If a timeout occurs before the user responds to the message box, the return value is HTMLID_TIMEOUT.

If a string is provided for displayInFutureText and the user unchecks the box, HTMLID_DONTASKAGAIN is ORed in to the return value.

Description

To provide context sensitive help, provide a non-zero value for the helpID parameter and call the HTMLSetHelp function to set the help file. The MB_HELP flag is ignored.

If you use an automatic timeout by providing a value greater than zero for the timeoutSeconds parameter, make the timeout long enough that the user has a chance to respond to the message. Automatic timeouts are best used to prevent a message box from preventing a task from continuing. Large timeout values such as 300 seconds (5 minutes) are effective.

The result of providing the displayInFutureText parameter is to display the text and have HTMLID_DONTASKAGAIN ORed in to the return value. The calling function is responsible for suppressing the message box in the future.

You can set the font used by the message box functions using the HTMLSetFont function. You can set the message box button justification (center or right) using the HTMLSetCenterButtons function.

HTML Tagging

The message text may contain simple HTML tagging. HTML text is identified by starting with the <HTML> tag and ending with the </HTML> tag. Only the <HTML>, <H1>, <H2>, <H3>, <H4>, <P>, <B>, <I>, <CODE>, <BIG>, <SMALL>, and <BR> tags are supported. Newlines are not supported in HTML text, so you must use the <BR> tag to break lines. The < and > characters are supported to display the less than and greater than characters.

For the best results, use the HTML tagging with restraint.

Custom Button Lists

You can specify the message box buttons using either a custom button list or the button flags, such as MB_OK. The button flags are ignored if a button list is supplied. To create a button list, create an HTMLButtonList array and for each button specify the name, ID number, and whether the button is the default button. The buttons are displayed in the order of the items in the button list array. The list must be terminated by an entry with an ID of -1.

Modeless Operation

When using the HTMLMessageBoxModeless functions, you can change the message text by calling GetDlgItem(HTMLID_MESSAGE_TEXT) and then SetWindowText. You can obtain the modeless return value by calling HTMLModelessReturnValue. You also need to provide a message loop so that the message box can continue to receive messages and you should check to see if the user has finished with the message box by calling HTMLModelessReturnValue within the message loop. A typical modeless message box handler is as follows:


   HWND     hParent, hMessage;
   MSG      msg;
   int      retVal;

   // display the message box
   hMessage = HTMLMessageBoxModeless(hParent, _T("<HTML>A <B>modeless</B> message box.</HTML>"));

   // do processing
   while (DoSomeProcessing())
   {
      // check to see if the user has canceled
      if ((retVal = HTMLModelessReturnValue(hMessage)) >= 0)
         break;
      while (PeekMessage(&msg, 0, 0, 0, PM_REMOVE))
      {
         TranslateMessage(&msg);
         DispatchMessage(&msg);
      }
   }

   // get returned value (and do whatever you want with it)
   retVal = HTMLModelessReturnValue(hMessage);

   // destroy the modeless dialog
   DestroyWindow(hMessage);   // DestroyWindow deletes dialog

Note that if the user dismisses a modeless message box, the window is hidden but not destroyed so the window handle is valid until you call DestroyWindow.

Sample Code

A typical message box:


   #include "CtlHtml.h"

   HTMLMessageBox(hParent, _T("This is a test."), _T("Custom Title"), HTMLMB_CONTINUE);

A typical message box

A typical message box with a Don't Display in Future check box (using MFC):


   HTMLMessageBox(_T("This is a test."), _T("Custom Title"), MB_OK, 
                _T("Don't display this message in the future."));

A typical message box with a Don't Display in Future check box

An HTML text message box with the program name for the title (using MFC):


   HTMLMessageBox(_T("<HTML>This is an example of<BR><B>HTML text</B>.</HTML>"), 
                _T("Custom Title"), HTMLMB_CANCEL | MB_ICONSTOP);

An HTML text message box with the program name for the title

A button list message box:


   HTMLButtonList buttonList[5];

   buttonList[0].Name = "&Apple";
   buttonList[0].ID   = 100;
   buttonList[0].IsDefault = TRUE;

   buttonList[1].Name = "&Banana";
   buttonList[1].ID   = 101;
   buttonList[1].IsDefault = FALSE;

   buttonList[2].Name = "&Carrot";
   buttonList[2].ID   = 102;
   buttonList[2].IsDefault = FALSE;

   buttonList[3].Name = "&Donut";
   buttonList[3].ID   = 103;
   buttonList[3].IsDefault = FALSE;

   buttonList[4].ID   = -1;

   HTMLMessageBox(hParent, _T("This message box has custom buttons."), 
                _T("Button List Test"), MB_ICONINFORMATION, 0, buttonList);

A button list message box